
<!DOCTYPE HTML>
<html lang="en" >
    <head>
        <meta charset="UTF-8">
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <title>Open API · GitBook</title>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="description" content="">
        <meta name="generator" content="GitBook 3.2.3">
        
        
        
    
    <link rel="stylesheet" href="../../gitbook/style.css">

    
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-highlight/website.css">
                
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-search/search.css">
                
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-fontsettings/website.css">
                
            
        

    

    
        
    
        
    
        
    
        
    
        
    
        
    

        
    
    
    <meta name="HandheldFriendly" content="true"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="../../gitbook/images/apple-touch-icon-precomposed-152.png">
    <link rel="shortcut icon" href="../../gitbook/images/favicon.ico" type="image/x-icon">

    
    <link rel="next" href="metrics.html" />
    
    
    <link rel="prev" href="validation.html" />
    

    </head>
    <body>
        
<div class="book">
    <div class="book-summary">
        
            
<div id="book-search-input" role="search">
    <input type="text" placeholder="Type to search" />
</div>

            
                <nav role="navigation">
                


<ul class="summary">
    
    

    

    
        
        
    
        <li class="chapter " data-level="1.1" data-path="../">
            
                <a href="../">
            
                    
                    Introduction
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="1.2" >
            
                <span>
            
                    
                    Topics
            
                </span>
            

            
            <ul class="articles">
                
    
        <li class="chapter " data-level="1.2.1" data-path="routes.html">
            
                <a href="routes.html">
            
                    
                    Routes
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="1.2.2" data-path="cli.html">
            
                <a href="cli.html">
            
                    
                    CLI
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="1.2.3" data-path="validation.html">
            
                <a href="validation.html">
            
                    
                    Validation
            
                </a>
            

            
        </li>
    
        <li class="chapter active" data-level="1.2.4" data-path="openapi.html">
            
                <a href="openapi.html">
            
                    
                    Open API
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="1.2.5" data-path="metrics.html">
            
                <a href="metrics.html">
            
                    
                    Metrics
            
                </a>
            

            
        </li>
    

            </ul>
            
        </li>
    

    

    <li class="divider"></li>

    <li>
        <a href="https://www.gitbook.com" target="blank" class="gitbook-link">
            Published with GitBook
        </a>
    </li>
</ul>


                </nav>
            
        
    </div>

    <div class="book-body">
        
            <div class="body-inner">
                
                    

<div class="book-header" role="navigation">
    

    <!-- Title -->
    <h1>
        <i class="fa fa-circle-o-notch fa-spin"></i>
        <a href=".." >Open API</a>
    </h1>
</div>




                    <div class="page-wrapper" tabindex="-1" role="main">
                        <div class="page-inner">
                            
<div id="book-search-results">
    <div class="search-noresults">
    
                                <section class="normal markdown-section">
                                
                                <h1 id="openapi">OpenAPI</h1>
<p>You&apos;ve upgraded your service to provide a new endpoint to create an echo message, i.e.</p>
<pre><code>curl -H &quot;Content-Type: application/json&quot; -X POST -d &apos;{&quot;name&quot;: &quot;alice&quot;, &quot;message&quot;: &quot;echo to myself&quot;}&apos; http://localhost:8080/echo
</code></pre><p>This is a complicated enpoint. To make it easy for your user, you decide to provide API documentation.
Nirvana has built-in support to generate openapi documentation. To generate the docs, you need to first
define where types come from. In our example, it&apos;s in the <code>api</code> package:</p>
<pre><code class="lang-go"><span class="hljs-keyword">package</span> api

<span class="hljs-comment">// Message defines the message to echo and to whom the message will be sent.</span>
<span class="hljs-comment">// +caicloud:openapi=true</span>
<span class="hljs-keyword">type</span> Message <span class="hljs-keyword">struct</span> {
    Name    <span class="hljs-keyword">string</span> <span class="hljs-string">`json:&quot;name&quot; validate:&quot;required&quot;`</span>
    Message <span class="hljs-keyword">string</span> <span class="hljs-string">`json:&quot;message&quot; validate:&quot;gt=10&quot;`</span>
}
</code></pre>
<p>Next step is to generate openapi definitions:</p>
<pre><code>openapi-gen \
  -i github.com/caicloud/nirvana/examples/getting-started/openapi/pkg/api \
  -p github.com/caicloud/nirvana/examples/getting-started/openapi/pkg/api
</code></pre><p>Finally, we can build our openapi specification:</p>
<pre><code class="lang-go">swagger, err := builder.BuildOpenAPISpec(&amp;echo, &amp;common.Config{
    Info: &amp;spec.Info{
        InfoProps: spec.InfoProps{
            Title:       <span class="hljs-string">&quot;echo server openAPI&quot;</span>,
            Description: <span class="hljs-string">&quot;This is open API documentation of echo server&quot;</span>,
            Contact: &amp;spec.ContactInfo{
                Name: <span class="hljs-string">&quot;nirvana&quot;</span>,
                URL:  <span class="hljs-string">&quot;https://gonirvana.io&quot;</span>,
            },
            License: &amp;spec.License{
                Name: <span class="hljs-string">&quot;Apache License, Version 2.0&quot;</span>,
                URL:  <span class="hljs-string">&quot;http://www.apache.org/licenses/LICENSE-2.0&quot;</span>,
            },
            Version: <span class="hljs-string">&quot;v1.0.0&quot;</span>,
        },
    },
    GetDefinitions: api.GetOpenAPIDefinitions,
})
<span class="hljs-keyword">if</span> err != <span class="hljs-literal">nil</span> {
    <span class="hljs-built_in">panic</span>(err)
}
encoder := json.NewEncoder(os.Stdout)
<span class="hljs-keyword">if</span> err := encoder.Encode(swagger); err != <span class="hljs-literal">nil</span> {
    <span class="hljs-built_in">panic</span>(err)
}
</code></pre>
<p>Now run the following command, we can generate our swagger.json file. Put it into <a href="https://editor.swagger.io/" target="_blank">https://editor.swagger.io/</a>,
we&apos;ll be able to view our generated API docs.</p>
<pre><code>go run ./examples/getting-started/openapi/echo.go &gt; /tmp/swagger.json
</code></pre><p>For full example code, see <a href="examples/getting-started/openapi">openapi</a>.</p>

                                
                                </section>
                            
    </div>
    <div class="search-results">
        <div class="has-results">
            
            <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
            <ul class="search-results-list"></ul>
            
        </div>
        <div class="no-results">
            
            <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
            
        </div>
    </div>
</div>

                        </div>
                    </div>
                
            </div>

            
                
                <a href="validation.html" class="navigation navigation-prev " aria-label="Previous page: Validation">
                    <i class="fa fa-angle-left"></i>
                </a>
                
                
                <a href="metrics.html" class="navigation navigation-next " aria-label="Next page: Metrics">
                    <i class="fa fa-angle-right"></i>
                </a>
                
            
        
    </div>

    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
            gitbook.page.hasChanged({"page":{"title":"Open API","level":"1.2.4","depth":2,"next":{"title":"Metrics","level":"1.2.5","depth":2,"path":"topics/metrics.md","ref":"topics/metrics.md","articles":[]},"previous":{"title":"Validation","level":"1.2.3","depth":2,"path":"topics/validation.md","ref":"topics/validation.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"language":"en","gitbook":"*"},"file":{"path":"topics/openapi.md","mtime":"2019-08-06T09:48:58.000Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2020-10-20T10:33:16.586Z"},"basePath":"..","book":{"language":"en"}});
        });
    </script>
</div>

        
    <script src="../../gitbook/gitbook.js"></script>
    <script src="../../gitbook/theme.js"></script>
    
        
        <script src="../../gitbook/gitbook-plugin-search/search-engine.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-search/search.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-sharing/buttons.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
        
    

    </body>
</html>

